<!DOCTYPE HTML PUBLIC "-//ORA//DTD CD HTML 3.2//EN">
<HTML>
<HEAD>
<TITLE>[Chapter 13] 13.6 Java Documentation Comment Syntax</TITLE>
<META NAME="author" CONTENT="David Flanagan">
<META NAME="date" CONTENT="Thu Jul 31 16:01:08 1997">
<META NAME="form" CONTENT="html">
<META NAME="metadata" CONTENT="dublincore.0.1">
<META NAME="objecttype" CONTENT="book part">
<META NAME="otheragent" CONTENT="gmat dbtohtml">
<META NAME="publisher" CONTENT="O'Reilly &amp; Associates, Inc.">
<META NAME="source" CONTENT="SGML">
<META NAME="subject" CONTENT="Java">
<META NAME="title" CONTENT="Java in a Nutshell">
<META HTTP-EQUIV="Content-Script-Type" CONTENT="text/javascript">
</HEAD>
<body vlink="#551a8b" alink="#ff0000" text="#000000" bgcolor="#FFFFFF" link="#0000ee">

<DIV CLASS=htmlnav>
<H1><a href='index.htm'><IMG SRC="gifs/smbanner.gif"
     ALT="Java in a Nutshell" border=0></a></H1>
<table width=515 border=0 cellpadding=0 cellspacing=0>
<tr>
<td width=172 align=left valign=top><A HREF="ch13_05.htm"><IMG SRC="gifs/txtpreva.gif" ALT="Previous" border=0></A></td>
<td width=171 align=center valign=top><B><FONT FACE="ARIEL,HELVETICA,HELV,SANSERIF" SIZE="-1">Chapter 13<br>Java Syntax</FONT></B></TD>
<td width=172 align=right valign=top><A HREF="ch14_01.htm"><IMG SRC="gifs/txtnexta.gif" ALT="Next" border=0></A></td>
</tr>
</table>

&nbsp;
<hr align=left width=515>
</DIV>
<DIV CLASS=sect1>
<h2 CLASS=sect1><A CLASS="TITLE" NAME="JNUT2-CH-13-SECT-6">13.6 Java Documentation Comment Syntax</A></h2>

<P CLASS=para>
<A NAME="CH13.COMMENTS-1"></A><A NAME="CH13.PROGRAMMING.2"></A><A NAME="CH13.DOC.COMMENTS1"></A><A NAME="CH13.DOC.COMMENT.MARK1"></A>The Java language supports special "doc comments," which
begin with <tt CLASS=literal>/**</tt> and end with <tt CLASS=literal>*/</tt>.  These comments are
not actually treated specially by the compiler, but can be
extracted and automatically turned into HTML documentation
by the <I CLASS=emphasis>javadoc</I> program.

<P CLASS=para>
Because the lines of a doc comment are embedded within a
Java comment, any leading spaces and asterisks (<tt CLASS=literal>*</tt>)
are stripped from each comment line before processing.  A
doc comment may contain HTML markup tags, such as &lt;PRE&gt; and
&lt;TT&gt; for code usage examples, but should not contain HTML
structural tags such as &lt;H2&gt; or &lt;HR&gt;.  Doc comments should
immediately precede the declaration of the class, field, or
method that they are associated with.  The first sentence of
a doc comment should be a summary sentence, suitable for
display on its own.  The following sentences may document
the feature in more detail.

<P CLASS=para>
Following the initial summary sentence and any additional
documentation, a doc comment may use special tags, which all
begin with the <tt CLASS=literal>@</tt> character and allow <I CLASS=emphasis>javadoc</I>
to provide additional formatting for the documentation.  The
available tags are listed below.  When you use a special
<I CLASS=emphasis>javadoc</I> tag, it must be the first thing on its line
within the doc comment.  The text that follows a tag may
span more than one line, and continues until the next
<I CLASS=emphasis>javadoc</I> tag is encountered or until the comment ends.
If you use more than one tag of the same type, they should
be on subsequent lines.  For example, a class with multiple
authors, or a method with multiple arguments would use
multiple <tt CLASS=literal>@author</tt> or <tt CLASS=literal>@param</tt> tags.

<P>
<DL CLASS=variablelist>
<DT CLASS=varlistentry><tt CLASS=literal>@see</tt> <I CLASS=emphasis>classname</I><br>
<DD>

<P CLASS=para>
This tag adds a "See Also:" entry to the documentation that
contains a hyperlink to the specified class.  It may be used
before classes, methods, or fields.

<p>
<DT CLASS=varlistentry><tt CLASS=literal>@see</tt> <I CLASS=emphasis>full-classname</I><br>
<DD>

<P CLASS=para>
This tag adds a "See Also:" entry to the documentation that
contains a hyperlink to the specified class.  It may be used
before classes, methods, or fields.

<p>
<DT CLASS=varlistentry><tt CLASS=literal>@see</tt> <I CLASS=emphasis>full-classname</I><tt CLASS=literal>#</tt><I CLASS=emphasis>method-name</I><br>
<DD>

<P CLASS=para>
 
This tag adds a "See Also:" entry to the documentation that
contains a hyperlink to the specified method of the
specified class.  It may be used before classes, methods, or
fields.

<p>
<DT CLASS=varlistentry><tt CLASS=literal>@version</tt> <I CLASS=emphasis>text</I><br>
<DD>

<P CLASS=para>
This tag adds a "Version:" entry containing the
specified text to the documentation.  May only be used
before a class definition.
<I CLASS=emphasis>javadoc</I> ignores this
tag unless the <tt CLASS=literal>-version</tt> command-line argument is
specified.

<p>
<DT CLASS=varlistentry><tt CLASS=literal>@author</tt> <I CLASS=emphasis>text</I><br>
<DD>

<P CLASS=para>
This tag adds an "Author:" entry containing the
specified text to the documentation.  May only be used
before a class definition.  <I CLASS=emphasis>javadoc</I> ignores this
tag unless the <tt CLASS=literal>-author</tt> command-line argument is
specified.

<p>
<DT CLASS=varlistentry><tt CLASS=literal>@param</tt> <I CLASS=emphasis>parameter-name</I> <I CLASS=emphasis>description</I><br>
<DD>

<P CLASS=para>
This tag adds the specified parameter and its specified
description to the "Parameters:" section of the current
method.  If the description is longer than one line, it may
be continued on the next.  May only be used before a method
definition.

<p>
<DT CLASS=varlistentry><tt CLASS=literal>@return</tt> <I CLASS=emphasis>description</I><br>
<DD>

<P CLASS=para>
Adds a "Returns:" section containing the specified
description to the documentation.  May only be used before a
method definition.

<p>
<DT CLASS=varlistentry><tt CLASS=literal>@exception</tt> <I CLASS=emphasis>full-classname</I> <I CLASS=emphasis>description</I><br>
<DD>

<P CLASS=para>
Adds a "Throws:" entry to the documentation.  The entry
contains the specified class name of the exception and the
description specified, which should explain the significance
of the exception.  May only be used before a method definition.

<p>
<DT CLASS=varlistentry><tt CLASS=literal>@deprecated</tt> <I CLASS=emphasis>explanation</I><br>
<DD>

<P CLASS=para>
As of Java 1.1, this tag specifies that the following
class, method, or field has been deprecated.  <I CLASS=emphasis>javac</I>
notes this information in the class file it produces and
issues a warning when a program uses the deprecated feature.
<I CLASS=emphasis>javadoc</I> adds a "Deprecated" entry to the documentation
that includes the specified explanation.

<p>
<DT CLASS=varlistentry><tt CLASS=literal>@since</tt> <I CLASS=emphasis>version</I><br>
<DD>

<P CLASS=para>
As of Java 1.1, this undocumented tag is used to
specify when the class, method, or field that follows it was
added to the API.  It should be followed by a version number
or other version specification.  The JDK 1.1 version of
<I CLASS=emphasis>javadoc</I> appears to ignore this tag.</DL>
</DIV>


<DIV CLASS=htmlnav>

<P>
<HR align=left width=515>
<table width=515 border=0 cellpadding=0 cellspacing=0>
<tr>
<td width=172 align=left valign=top><A HREF="ch13_05.htm"><IMG SRC="gifs/txtpreva.gif" ALT="Previous" border=0></A></td>
<td width=171 align=center valign=top><a href="index.htm"><img src='gifs/txthome.gif' border=0 alt='Home'></a></td>
<td width=172 align=right valign=top><A HREF="ch14_01.htm"><IMG SRC="gifs/txtnexta.gif" ALT="Next" border=0></A></td>
</tr>
<tr>
<td width=172 align=left valign=top>Reserved Words</td>
<td width=171 align=center valign=top><a href="index/idx_0.htm"><img src='gifs/index.gif' alt='Book Index' border=0></a></td>
<td width=172 align=right valign=top>System Properties</td>
</tr>
</table>
<hr align=left width=515>

<IMG SRC="gifs/smnavbar.gif" USEMAP="#map" BORDER=0> 
<MAP NAME="map"> 
<AREA SHAPE=RECT COORDS="0,0,108,15" HREF="../javanut/index.htm"
alt="Java in a Nutshell"> 
<AREA SHAPE=RECT COORDS="109,0,200,15" HREF="../langref/index.htm" 
alt="Java Language Reference"> 
<AREA SHAPE=RECT COORDS="203,0,290,15" HREF="../awt/index.htm" 
alt="Java AWT"> 
<AREA SHAPE=RECT COORDS="291,0,419,15" HREF="../fclass/index.htm" 
alt="Java Fundamental Classes"> 
<AREA SHAPE=RECT COORDS="421,0,514,15" HREF="../exp/index.htm" 
alt="Exploring Java"> 
</MAP>
</DIV>

</BODY>
</HTML>
